<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN""http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><title>Do It Simple Markup Language (DISML) 0.1</title><link rel="stylesheet" href="style.css" type="text/css" /><meta name="generator" content="DISML DSS2 0.1" /></head><body>
<h1>Do It Simple Markup Language (DISML) 0.1</h1>
<h2>Draft 2010-03-20</h2>
<p><b>Massei Francesco</b></p>
<p>&lt;<a href="mailto:fmassei@gmail.com">fmassei@gmail.com</a>&gt;</p>
<p><b>This version</b>: <a href=""></a></p>
<h1><a name="1">1. Status of this document</a></h1>
    <p>This is an intermediate working draft and is being actively revised.</p>
<h1><a name="2">2. Abstract</a></h1>
    <p>DISML is a human and machine friendly markup language, designed to be
    easily read and written by both users and software. It can be broadly used 
    in many environments for many scopes, from configuration files to internet 
    messaging to object persistence to data auditing.</p>
<h1><a name="3">3. Table of contents</a></h1>
    <ul>
        <li><a href="#1">1. Status of this document</a></li>
        <li><a href="#2">2. Abstract</a></li>
        <li><a href="#4">4. Introduction</a></li>
        <li><a href="#5">5. Goals</a><ul>
            <li><a href="#5.1">5.1. In short terms</a></li>
            <li><a href="#5.2">5.2. More precisely</a></li></ul></li>
        <li><a href="#6">6. Relation to XML, JSON, YAML, INI</a></li>
        <li><a href="#7">7. Terminology</a></li>
        <li><a href="#8">8. Preview</a></li>
        <li><a href="#9">9. Processing DISML Information</a><ul>
            <li><a href="#9.1">9.1. Conformant parsers</a></li>
            <li><a href="#9.2">9.2. Functions by level</a></li>
            <li><a href="#9.3">9.3. Compability</a></li></ul></li>
        <li><a href="#10">10. Syntax</a><ul>
            <li><a href="#10.1">10.1. Character encoding</a></li>
            <li><a href="#10.2">10.2. Header</a></li>
            <li><a href="#10.3">10.3. Elements</a></li>
            <li><a href="#10.4">10.4. Indentation</a></li>
            <li><a href="#10.5">10.5. Objects</a></li>
            <li><a href="#10.6">10.6. KV-Pairs</a></li>
            <li><a href="#10.7">10.7. Escaping</a></li></ul></li>
        <li><a href="#index">Index</a></li>
    </ul>
<h1><a name="4">4. Introduction</a></h1>
    <p>"Do It Simple Markup Language" (abbreviated DISML) is a data
    serialization language designed to be human and machine friendly.
    This specification is both an introduction to the DISML language and the 
    concepts supporting it; and also a complete reference of the information 
    needed to develop applications for processing DISML.
    The main design goal was to keep DISML as simple as possibile. 
    Some of the "key" features of other meta-languages are not even described
    in DISML, leaving maximum freedom to applications.</p>
<h1><a name="5">5. Goals</a></h1>
<h2><a name="5.1">5.1. In short terms..</a></h2>
    <p>The design goals for DISML are:
    <ul>
        <li>humans can easily read and write DISML documents</li>
        <li>machines can easily read and write DISML documents</li>
    </ul>
    Where "easily" means, in both cases, in a fast and natural way.</p>
<h2><a name="5.2">5.2. ... more precisely</a></h2>
    <p>An ideal markup language should:
    <ol>
        <li>be structured enough to permit the logical organization of human
        concept and mental structures (like <i>objects</i>, <i>attributes</i>,
        <i>hierarchy</i> and so on)</li>
        <li>be able to express this structures in the most efficient way for
        a machine to parse them, while in the most natural way for a human to 
        read and write them.</li>
        <li>eliminate (or at least reduce) for an application which
        uses it, both the language bonds that force hacks and work-arounds,
        and extra work to accomplish basilar tasks.</li>
    </ol>
    How DISML solves:
    <ol>
        <li>There are two main intrinsic structures in DISML: <i>objects</i> and
        <i>key-value pairs</i>. Objects are organized in a hierarchical way,
        and contain key-value pairs.<br />
        Informatically speaking, a DISML file is a <i>tree</i> which have
        objects on nodes and key-value pairs on leafs.</li>
        <li>A DISML file is so easy and with so few rules that reading and
        writing a file is incredibly fast for both a human and a machine.
        Probably there are a lot of non-standardized file structures that are
        very similar to a DISML file.</li>
        <li>A DISML file is very "free": there are very few rules to follow in 
        order to have a valid document. On the other hand, there are some rigid
        rules on parser implementations. The goal of this choice is to keep
        the final applications free to choose the desider balance between
        level of abstraction, functionality and computational weight.</li>
    </ol>
    </p>
<h1><a name="6">6. Relation to XML, JSON, YAML, INI</a></h1>
<p></p>
<h1><a name="7">7. Terminology</a></h1>
    <p>This specification uses key words in accordance with RFC2119 to indicate
    requirement level. In particular, the following words are used to describe
    the actions of a DISML processor:
    <ul>
        <li><b>may</b><br /> This word, or the adjective "optional", mean that
        conformant processors are permitted, but need not behave as
        described.</li>
        <li><b>should</b><br/> This word, or the adjective "recommended", mean
        that there could be reasons for a processor to deviate from the
        behavior described, but that such deviation could hurt interoperability
        and should therefore be advertised with appropriate notice.</li>
        <li><b>must</b><br /> This word, or the term "required" or "shall",
        mean that the behavior described is an absolute requirement of the
        specification.</li>
    </ul></p>
<h1><a name="8">8. Preview</a></h1>
    <p>Some valid DISML document examples:</p>
    <code>DISML 
glossary
    title="example glossary"
    GlossDiv
        title="S"
        GlossList
            GlossEntry
                ID="SGML"
                SortAs="SGML"
                GlossTerm="Standard Generalized Markup Language"
                Acronym="SGML"
                Abbrev="ISO 8879:1986"
                GlossDef
                    para= "A meta-markup language, used to create markup languages such as DocBook."
                    GlossSeeAlso="GML, XML"
                GlossSee="markup"</code>
    <i>Converted from a Json example @ http://www.json.org/example.html</i>
    <code>DISML 
invoice
    code = 34843
    date = 2001-01-23
    bill-to
        given = Chris
        family = Dumars
        address
            lines = 458 Walkman Dr. Suite #292
            city = Royal Oak
            state = MI
            postal = 48046
    product
        sku = BL394D
        quantity = 4
        description = Basketball
        price = 450.00
    product
        sku = BL4438H
        quantity = 1
        description = Super Hoop
        price = 2392.00
    tax = 251.42
    total = 4443.52
    comments = "Late afternoon is best. Backup contact is Nancy. Billsmer @ 338-4338"</code>
    <i>Converted from a YAML example @ http://www.yaml.org/start.html</i>
<h1><a name="9">9. Processing DISML Information</a></h1>
<h2><a name="9.1">9.1. Conformant parsers</a></h2>
    <p>To mantain the correct balance between needed functionalities and
    resource usage in a correct DISML file handling, the following
    <i>software levels</i> are defined:<ol>
        <li><b>Level 0</b>: the minimum set of functions to correctly read and
        write a DISML document.</li>
        <li><b>Level 1</b>: extension functions that manage character encoding,
        file encoding, data-type conversions and so on.</li>
        <li><b>Level 2</b>: extension functions to validate documents,
        convert to other formats and general utilities.</li>
    </ol>
    <p>Each conformant level-1 or level-2 parser must give the possibility to
    its users to include (and/or link) only level-0 and level-1 functions
    respectively.</p>
<h2><a name="9.2">9.2. Functions by level</a></h2>
<h2><a name="9.3">9.3. Compatibility</a></h2>
<h1><a name="9">10. Syntax</a></h1>
<h2><a name="10.1">10.1. Character encoding</a></h2>
    <p>No character encoding is specified, with the following exceptions:
    <ul>
        <li>Character defined in the file header, (like indentation, escape and
        comment character), must be contained in the 7-bit ASCII set.</li>
        <li>If a BOM is present before the header definition, a level 0 parser
        must skip it and procede without errors.</li>
    </ul></p>
<h2><a name="10.2">10.2. Header</a></h2>
    <p>A DISML file must begin with an header in the form:</p>
    <code>&lt;magic string&gt;&lt;indent character&gt;[&lt;escape character&gt;[&lt;comment character&gt;]]&lt;end of line sequence&gt;</code>
    <p><ul>
        <li><i>magic string</i><br />
        In the actual version it is defined as "DISML"</li>
        <li><i>indent character</i><br />
        It defines the indentation character. Tipically defined as space or tab,
        it can assume any value.</li>
        <li><i>escape character</i><br />
        If present, it defines which character escapes quotation marks and
        end-of-line (See: <a href="#10.7">10.7.Escaping</a>).
        The default character is '/'.</li>
        <li><i>comment character</i><br />
        If present, it defines which character defines the start of a comment
        line. The default character is '#'.</li>
        <li><i>end-of-line</i><br />
        The end-of-line sequence can be one of CR, CR/LF or LF. This sequence
        must be the same for any other line in the document.</li>
    </ul></p>
    <p>The strings defined below are all valid headers:</p>
    <code>
        "DISML "
        "DISML  \#"
        "DISMLabc"
    </code>
    <p>The first one defines a space as the indentation character, leaving the
    default value for the escape and comment ones. The second one explicitly
    set the default values for every character. The third one set 'a' as the 
    indentation character, 'b' as the escape one and 'c' as the comment one.</p>
<h2><a name="10.3">10.3. Elements</a></h2>
    <p>A DISML element can be an <i>object</i> or a key-value pair, named
    <i>KV-pair</i>.</p>
    <p>Each element is defined in a single line, and is preceded by its
    <i>indentation</i>.</p>
    <code>&lt;identation&gt;&lt;object | kv-pair&gt;</code>
<h2><a name="10.4">10.4. Indentation</a></h2>
    <p>The indentation is a number of indentation characters equal to the 
    hierarchical level of the element that follows. If two elements have the
    same indentation are considered brothers, father and son otherwise</p>
    <code>father
    son
    son
        grandson</code>
    <p>Having more than one indentation level between a father and its son must
    be considered an error.</p>
    <code>object
        error="too much indentation!"
    son="correct indentation"</code>
<h2><a name="10.5">10.5. Objects</a></h2>
    <p>An object is defined as:</p>
    <code>&lt;object name&gt;</code>
<h2><a name="10.6">10.6. KV-Pairs</a></h2>
    <p>A key-value pair is defined as:</p>
    <code>&lt;key&gt;=["]&lt;value&gt;["]</code>
    <p>The quotation marks may or not be present.</p>
<h2><a name="10.7">10.7. Escaping</a></h2>
    <p>A DISML escape sequence must only occurr in a kv-pair value definition.
    There are only two escapable characters:
    <ul>
        <li>The quotation mark, in case the value definition is surrounded by
        quotation marks</li>
        <li>The end-of-line sequence.</li>
    </ul></p>
    <p>A conformant parser must be able to read lines up to 256 characters. 
    Any line exceding this limit should be cut in more lines escaping the
    end-of-line characters.</p> 
    <code>object
    elem1=we like to say: "Yeah!"
    elem2="we like to say: \"Yeah!\""
    elem3="we like to write long lines too, breaking \
them up to increase readability and to be sure that our new DISML parser \
would not throw strange errors!"</code>
<h1><a name="Index">Index</a></h1>
</body></html>
